/**
 * Copyright 2009 Sergio Bossa
 *
 *    Licensed under the Apache License, Version 2.0 (the "License");
 *    you may not use this file except in compliance with the License.
 *    You may obtain a copy of the License at
 *
 *        http://www.apache.org/licenses/LICENSE-2.0
 *
 *    Unless required by applicable law or agreed to in writing, software
 *    distributed under the License is distributed on an "AS IS" BASIS,
 *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *    See the License for the specific language governing permissions and
 *    limitations under the License.
 */
package com.googlecode.actorom;

import com.googlecode.actorom.support.ActorCreationException;

/**
 * The topology is used to create {@link Actor} instances and keep track of them into a message-based system.
 *
 * @param <A> The type of the {@link Address} used for accessing {@link Actor}s.
 *
 * @author Sergio Bossa
 */
public interface Topology<A extends Address> {

    /**
     * Create an {@link Actor} with a specific identifier and handler object.
     * <br><br>
     * The string identifier is used to properly build the complete {@link Address},
     * and must be unique inside this topology.
     * <br><br>
     * The handler object is used to define the {@link Actor} behaviour by properly applying
     * annotations contained into the <code>com.googlecode.actorom.annotation</code> package.
     *
     * @param id The actor unique identifier.
     * @param handler The actor handler.
     * @return The actor address.
     * @throws ActorCreationException If unable to spawn the actor.
     */
    public A spawnActor(String id, Object handler) throws ActorCreationException;

    /**
     * Get the {@link Actor} corresponding to a given {@link Address}.<br>
     *
     * @param address The actor address.
     * @return The actor, or null if no actor is found.
     */
    public Actor getActor(A address);

    /**
     * Shutdown this topology, disposing all resources currently held.
     */
    public void shutdown();
}
